home *** CD-ROM | disk | FTP | other *** search
/ BMUG PD-ROM A / PD-ROM A.iso / Programming / Programming Languages / Gambit LISP / OPEN ME FIRST! < prev    next >
Encoding:
Text File  |  1991-01-28  |  11.4 KB  |  339 lines  |  [TEXT/gamI]
  1. Documentation for Gambit v1.51 for Macintosh
  2. --------------------------------------------
  3.  
  4. In this documentation, you will find information on the following
  5. applications:
  6.  
  7. - Gambit Interpreter
  8. - Gambit Compiler
  9. - Gambit Linker
  10.  
  11. All of these applications run on Mac+/SE/II computers.
  12.  
  13.  
  14. Gambit Interpreter
  15. ------------------
  16.  
  17. The Gambit Interpreter (GSI for short) is a Scheme interpreter that
  18. can be used to develop and debug Gambit Scheme programs.  GSI conforms
  19. to the IEEE-Scheme standard as well as the R3.99RS report.  In
  20. addition, GSI has the ability to dynamically load object files (i.e.
  21. files with a .O extension) produced by the Gambit compiler.  GSI has a
  22. minimal debugging environment that supports program interrupt, error
  23. resume and abort.  Gambit v1.51 implements exact arithmetic only
  24. (including bignums and rationals).  Real and complex numbers are not
  25. available.
  26.  
  27. When GSI is launched, it grabs the entire memory for its heap (GSI can
  28. run with as little as 1 Meg of memory).  Under Multifinder it is
  29. possible to limit the amount of memory used by GSI by changing GSI's
  30. memory requirement information with the finder's <cmd>-I command.
  31.  
  32. If present, the file "init.scm" is loaded when GSI is launched.  This
  33. file can be used to customize GSI to your own needs.
  34.  
  35. Most of the interaction with GSI's read-eval-print (REP) loop is done
  36. through the keyboard.  To evaluate an expression, place the caret
  37. after the end of the expression and press <enter>.  This will send the
  38. expression to the interpreter for evaluation and the result will be
  39. displayed in the interaction window.  In addition, it is possible to
  40. send arbitrary text to the interpreter by selecting it before pressing
  41. <enter>.  These evaluation mechanisms also work in windows attached to
  42. files (however the result is always displayed in the interaction
  43. window).  For example, if you are reading this file from GSI, place the
  44. caret after the closing parenthesis of (* 3 5) and press <enter>.  The
  45. value 15 should be printed on the interaction window.
  46.  
  47. The tab key can be used to move the caret to the appropriate indentation
  48. position.
  49.  
  50. Special keyboard commands are available to interact with the
  51. interpreter:
  52.  
  53. - <cmd>-.  Interrupts the current computation and starts a new REP loop
  54. - <cmd>-R  Resumes an interrupted computation
  55. - <cmd>-D  Returns to the previous REP loop (also acts as end-of-file)
  56. - <cmd>-T  Returns to the top-most REP loop
  57.  
  58.  
  59. Here is a transcript of a typical interaction with GSI (comments are
  60. marked with ";;;" and user input is in bold):
  61.  
  62. Gambit (v1.51)
  63.  
  64. Loading "init.scm"
  65.  
  66. : ®ÏÔ·‰ ¢Ê·„Ù¢©  ;;; load "fact.scm" file
  67. "fact.scm"
  68.  
  69. : ®Ê·„Ù ¥∞©  ;;; try it
  70. 815915283247897734345611269596115894272000000000
  71.  
  72. : ®ÙÚ·„ ʷ„Ù©  ;;; lets trace what fact is doing
  73. fact
  74.  
  75. : ®Ê·„Ù ±µ©
  76. |(fact 15)
  77. | (fact 14)
  78. |  (fact 13)
  79. |   (fact 12)
  80. |    (fact 11)
  81. |    |(fact 10)
  82. |    | (fact 9)
  83. |    |  (fact 8)
  84. |    |   (fact 7)
  85. |    |    (fact 6)
  86. |    |    |(fact 5)
  87. |    |    | (fact 4)
  88. |    |    |  (fact 3)
  89. |    |    |   (fact 2)
  90. |    |    |    (fact 1)
  91. |    |    |    <== 1
  92. |    |    |   <== 2
  93. |    |    |  <== 6
  94. |    |    | <== 24
  95. |    |    |<== 120
  96. |    |    <== 720
  97. |    |   <== 5040
  98. |    |  <== 40320
  99. |    | <== 362880
  100. |    |<== 3628800
  101. |    <== 39916800
  102. |   <== 479001600
  103. |  <== 6227020800
  104. | <== 87178291200
  105. |<== 1307674368000
  106. 1307674368000
  107.  
  108. : ®ÏÔ·‰ ¢È¢©  ;;; load "pi.O" file
  109. How many digits of pi do you want (0 to exit): ∑∞
  110. 3.1415926535897932384626433832795028841971693993751058209749445923078164
  111. How many digits of pi do you want (0 to exit): ∞
  112. "pi.O"
  113.  
  114. : ®ÒıÂÂÓÛ ∏ £Ù©  ;;; oops!, we haven't defined it yet...
  115.  
  116. *** ERROR, Unbound variable: queens
  117.  
  118.  
  119. 1:   ;;; user typed <cmd>-D here
  120. : ®ÏÔ·‰ ¢ÒıÂÂÓÛ¢©  ;;; load it!
  121. "queens.O"
  122.  
  123. : ®ÒıÂÂÓÛ ∏ £Ù©
  124. (4 2 7 3 6 8 5 1)
  125. (5 2 4 7 3 8 6 1)
  126. (3 6 4 2 8 5 7 1)
  127. (3 5 2 8 6 4 7 1)
  128. (5 7 1 3 8 6 4 2)
  129. (4 6 8 3 1 7 5 2)
  130. (3 6 8 1 4 7 5 2)
  131. (5 7 4 1 3 8 6 2)
  132. (5 3 8 4 7 1 6 2)
  133. (3 6 4 1 8 5 7 2)  ;;; user typed <cmd>-. here
  134.  
  135. *** INTERRUPT
  136.  
  137.  
  138. 1:   ;;; <cmd>-D
  139. : ®ÏÔ·‰ ¢ÙÚ¢©
  140. "tree.scm"
  141.  
  142. : ®ÙÚÂÂ≠‰ÈÛÏ·˘ ®„·ÏÏ≠˜ÈÙË≠ÈÓıÙ≠ÊÈÏ ¢Ê·„ÙÆÛ„Ì¢ Ú·‰©©
  143.               .                                             
  144.    .----------------------.                                 
  145.    .                      .                                 
  146. define     .-----------------------------.                  
  147.            .                             .                  
  148.          .---.         .-----------------------------------.
  149.          .   .         .                                   .
  150.        fact .--.  .----------.                            ()
  151.             .  .  .          .                              
  152.             n () if  .---------------.                      
  153.                      .               .                      
  154.                     .--.     .---------------.              
  155.                     .  .     .               .              
  156.                     < .--.   1     .--------------------.   
  157.                       .  .         .                    .   
  158.                       n .--.   .--------.              ()   
  159.                         .  .   .        .                   
  160.                         2 ()   * .-------------.            
  161.                                  .             .            
  162.                                  n       .-----------.      
  163.                                          .           .      
  164.                                      .-------.      ()      
  165.                                      .       .              
  166.                                    fact  .--------.         
  167.                                          .        .         
  168.                                         .--.     ()         
  169.                                         .  .                
  170.                                         - .--.              
  171.                                           .  .              
  172.                                           n .--.            
  173.                                             .  .            
  174.                                             1 ()            
  175. #[undefined]
  176.  
  177. : 
  178.  
  179.  
  180. Gambit Compiler
  181. ---------------
  182.  
  183. The Gambit Compiler (GSC for short) is used to compile a Scheme source
  184. program into a binary `object file' that can either be loaded by the
  185. Gambit Interpreter or turned into a full fledged Macintosh application
  186. with the Gambit Linker.
  187.  
  188. GSC needs at least 2.5 Megs to run.  A larger memory size is recommended
  189. to compile large Scheme programs.  If you do not have enough memory to
  190. compile a given program, split it into smaller files.
  191.  
  192. When launched, GSC will pop up a dialog box.  It is through this dialog
  193. box that you specify what file you want to compile and what compilation
  194. options to use.  The first parameter is the filename of the source file
  195. (you do not have to specify the extension `.scm').  The remaining
  196. parameters are the compilation options.
  197.  
  198. These options are accepted by GSC
  199.  
  200. verbose   Generate a trace of the compiler's actions on
  201.           the interaction window.
  202.  
  203. report    Produce global variable usage report on the
  204.           interaction window.  Each global variable used in
  205.           the program is listed with 4 flags that indicate if
  206.           the global variable is defined, referenced, mutated
  207.           and called.
  208.  
  209. asm       Produce the assembly language file on <source>.s .
  210.  
  211. pvm       Produce a listing of the PVM code for the program
  212.           on <source>.pvm .
  213.  
  214. stats     Generate code to gather runtime statistics on the
  215.           program.  The statistics will be output on the profile
  216.           file when the program is run.
  217.  
  218.  
  219. In addition to the standard Scheme special forms, the compiler accepts
  220. the following forms which can appear anywhere a `define' special form
  221. can appear:
  222.  
  223. (##declare <decl>...)
  224.  
  225.   See below for the list of accepted declarations.
  226.   The scope of the declaration extends to the end of the body it is in
  227.   or to the end of the program if it is at toplevel.
  228.  
  229. (##include "prog.scm")
  230.  
  231.   Read the expressions contained in the given file and splice them
  232.   into the program.
  233.  
  234. (##define-macro (name parm...) <body>)
  235.  
  236.   Define the name as a macro special form which expands into `body'.
  237.   The scope of the declaration extends to the end of the body it is in
  238.   or to the end of the program if it is at toplevel (unless it is
  239.   redefined before).
  240.  
  241.  
  242. The following declarations are accepted by the compiler:
  243.  
  244. (<dialect>)
  245.  
  246.   Use the given dialect's semantics.  <dialect> can be:
  247.   ieee-scheme, r4rs-scheme or multischeme.
  248.  
  249. ([not] lambda-lift)
  250.  
  251.   Lambda-lift (or don't lambda-lift) procedures.
  252.  
  253. (<strategy>)
  254.  
  255.   Select block compilation or separate compilation.  In block
  256.   compilation, the compiler can assume that all references to the
  257.   global variables defined in the current program are located in the
  258.   program itself.  <strategy> can be: block or separate.
  259.  
  260. ([not] standard-bindings <var>...)
  261.  
  262.   The given global variables are known (or not known) to be equal
  263.   to the value defined for them in the dialect (all variables defined
  264.   in the standard if none specified).
  265.  
  266. ([not] extended-bindings <var>...)
  267.  
  268.   The given global variables are known (or not known) to be equal
  269.   to the value defined for them in the runtime system (all variables
  270.   defined in the runtime if none specified).
  271.  
  272. ([not] safe)
  273.  
  274.   Generate (or don't generate) code that will prevent fatal runtime
  275.   errors.  Note that in `safe' mode certain semantic errors will not be
  276.   checked as long as they can't crash the system.  For example
  277.   the primitive `char=?' could disregard the type of its arguments in
  278.   `safe' (as well as `not safe') mode.
  279.  
  280. ([not] intr-checks)
  281.  
  282.   Generate (or don't generate) interrupt checks.  Interrupt checks are
  283.   used to signal the need for a garbage collection, to catch user
  284.   interrupts and also to check for stack overflows.  Interrupt checking
  285.   should not be turned off casually.
  286.  
  287. (<number-type> <prim>...)
  288.  
  289.   Numeric arguments and result of specified primitives are known to be
  290.   of the given type (all primitives if none specified).
  291.   <number-type> can be: generic or fixnum.
  292.  
  293.  
  294. The default declarations used by the compiler are:
  295.  
  296.   (ieee-scheme)
  297.   (lambda-lift)
  298.   (separate)
  299.   (not standard-bindings)
  300.   (not extended-bindings)
  301.   (not safe)
  302.   (intr-checks)
  303.   (generic)
  304.  
  305. These declarations are compatible with the IEEE-Scheme standard.
  306. Typically used declarations that enhance performance (at the cost of
  307. violating the IEEE-Scheme standard) are: (standard-bindings) and
  308. (fixnum).
  309.  
  310. The diagnostic messages produced by GSC are printed on the interaction
  311. window.
  312.  
  313. The code generated by GSC is very efficient.  Speedups of a factor of 100
  314. over interpreted code are not uncommon.
  315.  
  316.  
  317. A useful feature of object files is that they can be run by
  318. double-clicking them.  This is essentially equivalent to starting the
  319. interpreter and loading the given object file (except that the
  320. "init.scm" file is not loaded and a REP loop is not entered).
  321. As an example, exit from GSI and double-click the document file "pi.O".
  322.  
  323.  
  324. Gambit Linker
  325. -------------
  326.  
  327. The Gambit Linker is used to build a Macintosh application program
  328. from a runtime library and an arbitrary number of object files
  329. produced by the Gambit compiler.  The Gambit linker first prompts for
  330. the runtime library file and then for a set of object files.  The name
  331. of the application is the same as the name of the last object file to
  332. be linked with its `.O' extension stripped off.  For example, if you
  333. link the library `Runtime' with the object file `pi.O' you will get
  334. the application `pi' which you can then double-click to run.
  335.  
  336. When the linked program is launched, the effect is similar to loading
  337. each of the object files, in sequence, in the interpreter (except that
  338. the "init.scm" file is not loaded and a REP loop is not entered).
  339.